//
//  TimeZone.swift
//  Documentation
//
//  Created by Toj on 11/13/23.
//

/**
 TimeZone定义了时区的行为, 时区值表示相对格林威治标准时间(GMT)的时间偏移量(正或负)
 
 'TimeZone'提供了两个静态函数来获取时区值:
 'current'和'autoupdatingCurrent'.
 'autoupdatingCurrent'时区自动跟踪用户所做的更新.
 
 NOTE: 时区数据库条目(如"America/ los - angeles")是id, 而不是名称.
 时区名称的一个示例是"太平洋夏令时间".
 虽然许多"TimeZone"函数包含单词"name", 但它们指的是id.
 */
public struct TimeZone : Hashable, Equatable, ReferenceConvertible, Sendable {

    public typealias ReferenceType = NSTimeZone

    /// 当前时区
    public static var current: TimeZone { get }

    /// 当前时区
    /// 该方法会自动跟踪用户所做的更新.
    public static var autoupdatingCurrent: TimeZone { get }

    /// 初始化
    /// 初始化: 通过id
    /// NOTE: 如果'identifier'是未知标识符, 则返回'nil'.
    public init?(identifier: String)
    
    /// 初始化: 相对于格林尼治标准时间(GMT)的偏移seconds秒数
    /// e.g.: TimeZone(secondsFromGMT: (60 * 60 * 8)(8小时))
    /// NOTE: 如果相对于seconds秒数的时区无效则返回nil
    public init?(secondsFromGMT seconds: Int)

    /// 初始化: 缩写标识的时区(不建议使用)
    /// NOTE: 如果缩写时区无效则返回nil
    public init?(abbreviation: String)

    /// 获取时区的id
    public var identifier: String { get }

    /// 当前时区与格林威治标准时间的秒差
    /// 默认当前时间
    public func secondsFromGMT(for date: Date = Date()) -> Int

    /// 时区的缩写
    public func abbreviation(for date: Date = Date()) -> String?

    /// 夏令时
    public func isDaylightSavingTime(for date: Date = Date()) -> Bool

    /// 指定日期的夏令时偏移量
    public func daylightSavingTimeOffset(for date: Date = Date()) -> TimeInterval

    /// 指定日期之后的下一个夏令时过渡的日期
    public func nextDaylightSavingTimeTransition(after date: Date) -> Date?

    /// 系统已知的所有时区的id
    public static var knownTimeZoneIdentifiers: [String] { get }

    /// 缩写与时区id的映射字典
    public static var abbreviationDictionary: [String : String]

    /// 时区数据的版本
    public static var timeZoneDataVersion: String { get }

    /// 当前日期之后的下一个夏令时过渡的日期
    public var nextDaylightSavingTimeTransition: Date? { get }

    /// 指定语言环境本地化的时区名称
    public func localizedName(for style: NSTimeZone.NameStyle, locale: Locale?) -> String?

    /// 格林尼治标准时间 时区
    @available(macOS 13, iOS 16, tvOS 16, watchOS 9, *)
    public static var gmt: TimeZone { get }

    public func hash(into hasher: inout Hasher)
    public static func == (lhs: TimeZone, rhs: TimeZone) -> Bool
    public var hashValue: Int { get }
}
